---
title: 自动补全
---

<Info>**协议修订版**：2024-11-05</Info>

模型上下文协议（MCP）为服务器提供了一种标准化的方式，为提示和资源 URI 提供参数自动补全建议。这使得用户在输入参数值时能够获得类似 IDE 的丰富上下文建议体验。

## 用户交互模型

MCP 中的自动补全旨在支持类似 IDE 代码补全的交互式用户体验。

例如，应用程序可以在用户输入时通过下拉菜单或弹出窗口显示补全建议，并支持过滤和选择可用选项。

然而，实现可以自由选择适合其需求的任何界面模式来暴露自动补全——协议本身不强制要求特定的用户交互模型。

## 协议消息

### 请求补全

要获取补全建议，客户端发送 `completion/complete` 请求，通过引用类型指定正在补全的内容：

**请求：**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",
      "name": "code_review"
    },
    "argument": {
      "name": "language",
      "value": "py"
    }
  }
}
```

**响应：**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "completion": {
      "values": ["python", "pytorch", "pyside"],
      "total": 10,
      "hasMore": true
    }
  }
}
```

### 引用类型

协议支持两种补全引用类型：

| 类型           | 描述                     | 示例                                                 |
| -------------- | ------------------------ | --------------------------------------------------- |
| `ref/prompt`   | 按名称引用提示           | `{"type": "ref/prompt", "name": "code_review"}`     |
| `ref/resource` | 引用资源 URI             | `{"type": "ref/resource", "uri": "file:///{path}"}` |

### 补全结果

服务器返回按相关性排序的补全值数组，包含：

- 每响应最多 100 项
- 可选的可用匹配总数
- 指示是否存在额外结果的布尔值

## 消息流程

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Note over Client: 用户输入参数
    Client->>Server: completion/complete
    Server-->>Client: 补全建议

    Note over Client: 用户继续输入
    Client->>Server: completion/complete
    Server-->>Client: 优化后的建议
```

## 数据类型

### 补全请求

- `ref`：`PromptReference` 或 `ResourceReference`
- `argument`：包含以下内容的对象：
  - `name`：参数名称
  - `value`：当前值

### 补全结果

- `completion`：包含以下内容的对象：
  - `values`：建议数组（最多 100 项）
  - `total`：可选的匹配总数
  - `hasMore`：额外结果标志

## 实现注意事项

1. 服务器 **应该**：

   - 按相关性排序返回建议
   - 在适当情况下实现模糊匹配
   - 对补全请求进行速率限制
   - 验证所有输入

2. 客户端 **应该**：
   - 防抖快速补全请求
   - 在适当情况下缓存补全结果
   - 优雅处理缺失或部分结果

## 安全

实现 **必须**：

- 验证所有补全输入
- 实施适当的速率限制
- 控制对敏感建议的访问
- 防止基于补全的信息泄露